home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_xemacs.idb / usr / freeware / lib / xemacs-20.4 / info / lispref.info-19.z / lispref.info-19
Encoding:
GNU Info File  |  1998-05-21  |  47.5 KB  |  1,134 lines
  1. This is Info file ../../info/lispref.info, produced by Makeinfo version
  2. 1.68 from the input file lispref.texi.
  3.  
  4.    Edition History:
  5.  
  6.    GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
  7. Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
  8. Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
  9. XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
  10. GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
  11. Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
  12. Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
  13. Reference Manual (for 19.15 and 20.1, 20.2) v3.2, April, May 1997
  14.  
  15.    Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
  16. Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
  17. Copyright (C) 1995, 1996 Ben Wing.
  18.  
  19.    Permission is granted to make and distribute verbatim copies of this
  20. manual provided the copyright notice and this permission notice are
  21. preserved on all copies.
  22.  
  23.    Permission is granted to copy and distribute modified versions of
  24. this manual under the conditions for verbatim copying, provided that the
  25. entire resulting derived work is distributed under the terms of a
  26. permission notice identical to this one.
  27.  
  28.    Permission is granted to copy and distribute translations of this
  29. manual into another language, under the above conditions for modified
  30. versions, except that this permission notice may be stated in a
  31. translation approved by the Foundation.
  32.  
  33.    Permission is granted to copy and distribute modified versions of
  34. this manual under the conditions for verbatim copying, provided also
  35. that the section entitled "GNU General Public License" is included
  36. exactly as in the original, and provided that the entire resulting
  37. derived work is distributed under the terms of a permission notice
  38. identical to this one.
  39.  
  40.    Permission is granted to copy and distribute translations of this
  41. manual into another language, under the above conditions for modified
  42. versions, except that the section entitled "GNU General Public License"
  43. may be included in a translation approved by the Free Software
  44. Foundation instead of in the original English.
  45.  
  46. 
  47. File: lispref.info,  Node: Menubar,  Next: Modifying Menus,  Prev: Menubar Format,  Up: Menus
  48.  
  49. Menubar
  50. =======
  51.  
  52.  - Variable: current-menubar
  53.      This variable holds the description of the current menubar.  This
  54.      may be buffer-local.  When the menubar is changed, the function
  55.      `set-menubar-dirty-flag' has to be called in order for the menubar
  56.      to be updated on the screen.
  57.  
  58.  - Constant: default-menubar
  59.      This variable holds the menubar description of the menubar that is
  60.      visible at startup.  This is the value that `current-menubar' has
  61.      at startup.
  62.  
  63.  - Function: set-menubar-dirty-flag
  64.      This function tells XEmacs that the menubar widget has to be
  65.      updated.  Changes to the menubar will generally not be visible
  66.      until this function is called.
  67.  
  68.    The following convenience functions are provided for setting the
  69. menubar.  They are equivalent to doing the appropriate action to change
  70. `current-menubar', and then calling `set-menubar-dirty-flag'.  Note
  71. that these functions copy their argument using `copy-sequence'.
  72.  
  73.  - Function: set-menubar MENUBAR
  74.      This function sets the default menubar to be MENUBAR (*note Menu
  75.      Format::.).  This is the menubar that will be visible in buffers
  76.      that have not defined their own, buffer-local menubar.
  77.  
  78.  - Function: set-buffer-menubar MENUBAR
  79.      This function sets the buffer-local menubar to be MENUBAR.  This
  80.      does not change the menubar in any buffers other than the current
  81.      one.
  82.  
  83.    Miscellaneous:
  84.  
  85.  - Variable: menubar-show-keybindings
  86.      If true, the menubar will display keyboard equivalents.  If false,
  87.      only the command names will be displayed.
  88.  
  89.  - Variable: activate-menubar-hook
  90.      Function or functions called before a menubar menu is pulled down.
  91.      These functions are called with no arguments, and should
  92.      interrogate and modify the value of `current-menubar' as desired.
  93.  
  94.      The functions on this hook are invoked after the mouse goes down,
  95.      but before the menu is mapped, and may be used to activate,
  96.      deactivate, add, or delete items from the menus.  However, using a
  97.      filter (with the `:filter' keyword in a menu description) is
  98.      generally a more efficient way of accomplishing the same thing,
  99.      because the filter is invoked only when the actual menu goes down.
  100.      With a complex menu, there can be a quite noticeable and
  101.      sometimes aggravating delay if all menu modification is
  102.      implemented using the `activate-menubar-hook'.  See above.
  103.  
  104.      These functions may return the symbol `t' to assert that they have
  105.      made no changes to the menubar.  If any other value is returned,
  106.      the menubar is recomputed.  If `t' is returned but the menubar has
  107.      been changed, then the changes may not show up right away.
  108.      Returning `nil' when the menubar has not changed is not so bad;
  109.      more computation will be done, but redisplay of the menubar will
  110.      still be performed optimally.
  111.  
  112.  - Variable: menu-no-selection-hook
  113.      Function or functions to call when a menu or dialog box is
  114.      dismissed without a selection having been made.
  115.  
  116. 
  117. File: lispref.info,  Node: Modifying Menus,  Next: Pop-Up Menus,  Prev: Menubar,  Up: Menus
  118.  
  119. Modifying Menus
  120. ===============
  121.  
  122.    The following functions are provided to modify the menubar of one of
  123. its submenus.  Note that these functions modify the menu in-place,
  124. rather than copying it and making a new menu.
  125.  
  126.    Some of these functions take a "menu path", which is a list of
  127. strings identifying the menu to be modified.  For example, `("File")'
  128. names the top-level "File" menu.  `("File" "Foo")' names a hypothetical
  129. submenu of "File".
  130.  
  131.    Others take a "menu item path", which is similar to a menu path but
  132. also specifies a particular item to be modified.  For example, `("File"
  133. "Save")' means the menu item called "Save" under the top-level "File"
  134. menu.  `("Menu" "Foo" "Item")' means the menu item called "Item" under
  135. the "Foo" submenu of "Menu".
  136.  
  137.  - Function: add-submenu MENU-PATH SUBMENU &optional BEFORE
  138.      This function adds a menu to the menubar or one of its submenus.
  139.      If the named menu exists already, it is changed.
  140.  
  141.      MENU-PATH identifies the menu under which the new menu should be
  142.      inserted.  If MENU-PATH is `nil', then the menu will be added to
  143.      the menubar itself.
  144.  
  145.      SUBMENU is the new menu to add (*note Menu Format::.).
  146.  
  147.      BEFORE, if provided, is the name of a menu before which this menu
  148.      should be added, if this menu is not on its parent already.  If
  149.      the menu is already present, it will not be moved.
  150.  
  151.  - Function: add-menu-button MENU-PATH MENU-LEAF &optional BEFORE
  152.      This function adds a menu item to some menu, creating the menu
  153.      first if necessary.  If the named item exists already, it is
  154.      changed.
  155.  
  156.      MENU-PATH identifies the menu under which the new menu item should
  157.      be inserted.
  158.  
  159.      MENU-LEAF is a menubar leaf node (*note Menu Format::.).
  160.  
  161.      BEFORE, if provided, is the name of a menu before which this item
  162.      should be added, if this item is not on the menu already.  If the
  163.      item is already present, it will not be moved.
  164.  
  165.  - Function: delete-menu-item MENU-ITEM-PATH
  166.      This function removes the menu item specified by MENU-ITEM-PATH
  167.      from the menu hierarchy.
  168.  
  169.  - Function: enable-menu-item MENU-ITEM-PATH
  170.      This function makes the menu item specified by MENU-ITEM-PATH be
  171.      selectable.
  172.  
  173.  - Function: disable-menu-item MENU-ITEM-PATH
  174.      This function makes the menu item specified by MENU-ITEM-PATH be
  175.      unselectable.
  176.  
  177.  - Function: relabel-menu-item MENU-ITEM-PATH NEW-NAME
  178.      This function changes the string of the menu item specified by
  179.      MENU-ITEM-PATH.  NEW-NAME is the string that the menu item will be
  180.      printed as from now on.
  181.  
  182.    The following function can be used to search for a particular item in
  183. a menubar specification, given a path to the item.
  184.  
  185.  - Function: find-menu-item MENUBAR MENU-ITEM-PATH &optional PARENT
  186.      This function searches MENUBAR for the item given by
  187.      MENU-ITEM-PATH starting from PARENT (`nil' means start at the top
  188.      of MENUBAR).  This function returns `(ITEM . PARENT)', where
  189.      PARENT is the immediate parent of the item found (a menu
  190.      description), and ITEM is either a vector, list, or string,
  191.      depending on the nature of the menu item.
  192.  
  193.      This function signals an error if the item is not found.
  194.  
  195.    The following deprecated functions are also documented, so that
  196. existing code can be understood.  You should not use these functions in
  197. new code.
  198.  
  199.  - Function: add-menu MENU-PATH MENU-NAME MENU-ITEMS &optional BEFORE
  200.      This function adds a menu to the menubar or one of its submenus.
  201.      If the named menu exists already, it is changed.  This is
  202.      obsolete; use `add-submenu' instead.
  203.  
  204.      MENU-PATH identifies the menu under which the new menu should be
  205.      inserted.  If MENU-PATH is `nil', then the menu will be added to
  206.      the menubar itself.
  207.  
  208.      MENU-NAME is the string naming the menu to be added; MENU-ITEMS is
  209.      a list of menu items, strings, and submenus.  These two arguments
  210.      are the same as the first and following elements of a menu
  211.      description (*note Menu Format::.).
  212.  
  213.      BEFORE, if provided, is the name of a menu before which this menu
  214.      should be added, if this menu is not on its parent already.  If the
  215.      menu is already present, it will not be moved.
  216.  
  217.  - Function: add-menu-item MENU-PATH ITEM-NAME FUNCTION ENABLED-P
  218.           &optional BEFORE
  219.      This function adds a menu item to some menu, creating the menu
  220.      first if necessary.  If the named item exists already, it is
  221.      changed.  This is obsolete; use `add-menu-button' instead.
  222.  
  223.      MENU-PATH identifies the menu under which the new menu item should
  224.      be inserted. ITEM-NAME, FUNCTION, and ENABLED-P are the first,
  225.      second, and third elements of a menu item vector (*note Menu
  226.      Format::.).
  227.  
  228.      BEFORE, if provided, is the name of a menu item before which this
  229.      item should be added, if this item is not on the menu already.  If
  230.      the item is already present, it will not be moved.
  231.  
  232. 
  233. File: lispref.info,  Node: Menu Filters,  Next: Menu Accelerators,  Prev: Pop-Up Menus,  Up: Menus
  234.  
  235. Menu Filters
  236. ============
  237.  
  238.    The following filter functions are provided for use in
  239. `default-menubar'.  You may want to use them in your own menubar
  240. description.
  241.  
  242.  - Function: file-menu-filter MENU-ITEMS
  243.      This function changes the arguments and sensitivity of these File
  244.      menu items:
  245.  
  246.     `Delete Buffer'
  247.           Has the name of the current buffer appended to it.
  248.  
  249.     `Print Buffer'
  250.           Has the name of the current buffer appended to it.
  251.  
  252.     `Pretty-Print Buffer'
  253.           Has the name of the current buffer appended to it.
  254.  
  255.     `Save Buffer'
  256.           Has the name of the current buffer appended to it, and is
  257.           sensitive only when the current buffer is modified.
  258.  
  259.     `Revert Buffer'
  260.           Has the name of the current buffer appended to it, and is
  261.           sensitive only when the current buffer has a file.
  262.  
  263.     `Delete Frame'
  264.           Sensitive only when there is more than one visible frame.
  265.  
  266.  - Function: edit-menu-filter MENU-ITEMS
  267.      This function changes the arguments and sensitivity of these Edit
  268.      menu items:
  269.  
  270.     `Cut'
  271.           Sensitive only when XEmacs owns the primary X Selection (if
  272.           `zmacs-regions' is `t', this is equivalent to saying that
  273.           there is a region selected).
  274.  
  275.     `Copy'
  276.           Sensitive only when XEmacs owns the primary X Selection.
  277.  
  278.     `Clear'
  279.           Sensitive only when XEmacs owns the primary X Selection.
  280.  
  281.     `Paste'
  282.           Sensitive only when there is an owner for the X Clipboard
  283.           Selection.
  284.  
  285.     `Undo'
  286.           Sensitive only when there is undo information.  While in the
  287.           midst of an undo, this is changed to `Undo More'.
  288.  
  289.  - Function: buffers-menu-filter MENU-ITEMS
  290.      This function sets up the Buffers menu.  *Note Buffers Menu:: for
  291.      more information.
  292.  
  293. 
  294. File: lispref.info,  Node: Pop-Up Menus,  Next: Menu Filters,  Prev: Modifying Menus,  Up: Menus
  295.  
  296. Pop-Up Menus
  297. ============
  298.  
  299.  - Function: popup-menu MENU-DESC
  300.      This function pops up a menu specified by MENU-DESC, which is a
  301.      menu description (*note Menu Format::.).  The menu is displayed at
  302.      the current mouse position.
  303.  
  304.  - Function: popup-menu-up-p
  305.      This function returns `t' if a pop-up menu is up, `nil' otherwise.
  306.  
  307.  - Variable: popup-menu-titles
  308.      If true (the default), pop-up menus will have title bars at the
  309.      top.
  310.  
  311.    Some machinery is provided that attempts to provide a higher-level
  312. mechanism onto pop-up menus.  This only works if you do not redefine
  313. the binding for button3.
  314.  
  315.  - Command: popup-mode-menu
  316.      This function pops up a menu of global and mode-specific commands.
  317.      The menu is computed by combining `global-popup-menu' and
  318.      `mode-popup-menu'.  This is the default binding for button3.  You
  319.      should generally not change this binding.
  320.  
  321.  - Variable: global-popup-menu
  322.      This holds the global popup menu.  This is present in all modes.
  323.      (This is `nil' by default.)
  324.  
  325.  - Variable: mode-popup-menu
  326.      The mode-specific popup menu.  Automatically buffer local.  This
  327.      is appended to the default items in `global-popup-menu'.
  328.  
  329.  - Constant: default-popup-menu
  330.      This holds the default value of `mode-popup-menu'.
  331.  
  332.  - Variable: activate-popup-menu-hook
  333.      Function or functions run before a mode-specific popup menu is made
  334.      visible.  These functions are called with no arguments, and should
  335.      interrogate and modify the value of `global-popup-menu' or
  336.      `mode-popup-menu' as desired.  Note: this hook is only run if you
  337.      use `popup-mode-menu' for activating the global and mode-specific
  338.      commands; if you have your own binding for button3, this hook
  339.      won't be run.
  340.  
  341.    The following convenience functions are provided for displaying
  342. pop-up menus.
  343.  
  344.  - Function: popup-buffer-menu EVENT
  345.      This function pops up a copy of the `Buffers' menu (from the
  346.      menubar) where the mouse is clicked.
  347.  
  348.  - Function: popup-menubar-menu EVENT
  349.      This function pops up a copy of menu that also appears in the
  350.      menubar.
  351.  
  352. 
  353. File: lispref.info,  Node: Menu Accelerators,  Next: Buffers Menu,  Prev: Menu Filters,  Up: Menus
  354.  
  355. Menu Accelerators
  356. =================
  357.  
  358.    Menu accelerators are keyboard shortcuts for accessing the menubar.
  359. Accelerator keys can be specified for menus as well as for menu items.
  360. An accelerator key for a menu is used to activate that menu when it
  361. appears as a submenu of another menu.  An accelerator key for a menu
  362. item is used to activate that item.
  363.  
  364. * Menu:
  365.  
  366. * Creating Menu Accelerators::    How to add accelerator keys to a menu.
  367. * Keyboard Menu Traversal::    How to use and modify the keys which are used
  368.                 to traverse the menu structure.
  369. * Menu Accelerator Functions::    Functions for working with menu accelerators.
  370.  
  371. 
  372. File: lispref.info,  Node: Creating Menu Accelerators,  Next: Keyboard Menu Traversal,  Up: Menu Accelerators
  373.  
  374. Creating Menu Accelerators
  375. --------------------------
  376.  
  377.    Menu accelerators are specified as part of the menubar format using
  378. the :accelerator tag to specify a key or by placing "%_" in the menu or
  379. menu item name prior to the letter which is to be used as the
  380. accelerator key.  The advantage of the second method is that the menu
  381. rendering code then knows to draw an underline under that character,
  382. which is the canonical way of indicating an accelerator key to a user.
  383.  
  384.    For example, the command
  385.  
  386.      (add-submenu nil '("%_Test"
  387.                 ["One" (insert "1") :accelerator ?1 :active t]
  388.                 ["%_Two" (insert "2") t]
  389.                 ["%_3" (insert "3") t]))
  390.  
  391.    will add a new menu to the top level menubar.  The new menu can be
  392. reached by pressing "t" while the top level menubar is active.  When
  393. the menu is active, pressing "1" will activate the first item and
  394. insert the character "1" into the buffer.  Pressing "2" will activate
  395. the second item and insert the character "2" into the buffer.  Pressing
  396. "3" will activate the third item and insert the character "3" into the
  397. buffer.
  398.  
  399.    It is possible to activate the top level menubar itself using
  400. accelerator keys.  *Note Menu Accelerator Functions::.
  401.  
  402. 
  403. File: lispref.info,  Node: Keyboard Menu Traversal,  Next: Menu Accelerator Functions,  Prev: Creating Menu Accelerators,  Up: Menu Accelerators
  404.  
  405. Keyboard Menu Traversal
  406. -----------------------
  407.  
  408.    In addition to immediately activating a menu or menu item, the
  409. keyboard can be used to traverse the menus without activating items.
  410. The keyboard arrow keys, the return key and the escape key are defined
  411. to traverse the menus in a way that should be familiar to users of any
  412. of a certain family of popular PC operating systems.
  413.  
  414.    This behaviour can be changed by modifying the bindings in
  415. menu-accelerator-map.  At this point, the online help is your best bet
  416. for more information about how to modify the menu traversal keys.
  417.  
  418. 
  419. File: lispref.info,  Node: Menu Accelerator Functions,  Prev: Keyboard Menu Traversal,  Up: Menu Accelerators
  420.  
  421. Menu Accelerator Functions
  422. --------------------------
  423.  
  424.  - Function: accelerate-menu
  425.      Make the menubar immediately active and place the cursor on the
  426.      left most entry in the top level menu.  Menu items can be selected
  427.      as usual.
  428.  
  429.  - Variable: menu-accelerator-enabled
  430.      Whether menu accelerator keys can cause the menubar to become
  431.      active.
  432.  
  433.      If `menu-force' or `menu-fallback', then menu accelerator keys can
  434.      be used to activate the top level menu.  Once the menubar becomes
  435.      active, the accelerator keys can be used regardless of the value
  436.      of this variable.
  437.  
  438.      `menu-force' is used to indicate that the menu accelerator key
  439.      takes precedence over bindings in the current keymap(s).
  440.      `menu-fallback' means that bindings in the current keymap take
  441.      precedence over menu accelerator keys.  Thus a top level menu with
  442.      an accelerator of "T" would be activated on a keypress of Meta-t
  443.      if MENU-ACCELERATOR-ENABLED is `menu-force'.  However, if
  444.      MENU-ACCELERATOR-ENABLED is `menu-fallback', then Meta-t will not
  445.      activate the menubar and will instead run the function
  446.      transpose-words, to which it is normally bound.
  447.  
  448.      The default value is `nil'.
  449.  
  450.      See also MENU-ACCELERATOR-MODIFIERS and MENU-ACCELERATOR-PREFIX.
  451.  
  452.  - Variable: menu-accelerator-map
  453.      Keymap consulted to determine the commands to run in response to
  454.      keypresses occurring while the menubar is active.  *Note Keyboard
  455.      Menu Traversal::.
  456.  
  457.  - Variable: menu-accelerator-modifiers
  458.      A list of modifier keys which must be pressed in addition to a
  459.      valid menu accelerator in order for the top level menu to be
  460.      activated in response to a keystroke.  The default value of
  461.      `(meta)' mirrors the useage of the alt key as a menu accelerator
  462.      in popular PC operating systems.
  463.  
  464.      The modifier keys in MENU-ACCELERATOR-MODIFIERS must match exactly
  465.      the modifiers present in the keypress.  The only exception is that
  466.      the shift modifier is accepted in conjunction with alphabetic keys
  467.      even if it is not a menu accelerator modifier.
  468.  
  469.      See also MENU-ACCELERATOR-ENABLED and MENU-ACCELERATOR-PREFIX.
  470.  
  471.  - Variable: menu-accelerator-prefix
  472.      Prefix key(s) that must be typed before menu accelerators will be
  473.      activated.  Must be a valid key descriptor.
  474.  
  475.      The default value is `nil'.
  476.  
  477.      (setq menu-accelerator-prefix ?\C-x)
  478.      (setq menu-accelerator-modifiers '(meta control))
  479.      (setq menu-accelerator-enabled 'menu-force)
  480.      (add-submenu nil '("%_Test"
  481.                 ["One" (insert "1") :accelerator ?1 :active t]
  482.                 ["%_Two" (insert "2") t]
  483.                 ["%_3" (insert "3") t]))
  484.  
  485.    will add the menu "Test" to the top level menubar.  Pressing C-x
  486. followed by C-M-T will activate the menubar and display the "Test"
  487. menu.  Pressing C-M-T by itself will not activate the menubar.  Neither
  488. will pressing C-x followed by anything else.
  489.  
  490. 
  491. File: lispref.info,  Node: Buffers Menu,  Prev: Menu Accelerators,  Up: Menus
  492.  
  493. Buffers Menu
  494. ============
  495.  
  496.    The following options control how the `Buffers' menu is displayed.
  497. This is a list of all (or a subset of) the buffers currently in
  498. existence, and is updated dynamically.
  499.  
  500.  - User Option: buffers-menu-max-size
  501.      This user option holds the maximum number of entries which may
  502.      appear on the `Buffers' menu.  If this is 10, then only the ten
  503.      most-recently-selected buffers will be shown.  If this is `nil',
  504.      then all buffers will be shown.  Setting this to a large number or
  505.      `nil' will slow down menu responsiveness.
  506.  
  507.  - Function: format-buffers-menu-line BUFFER
  508.      This function returns a string to represent BUFFER in the
  509.      `Buffers' menu.  `nil' means the buffer shouldn't be listed.  You
  510.      can redefine this.
  511.  
  512.  - User Option: complex-buffers-menu-p
  513.      If true, the `Buffers' menu will contain several commands, as
  514.      submenus of each buffer line.  If this is false, then there will
  515.      be only one command: select that buffer.
  516.  
  517.  - User Option: buffers-menu-switch-to-buffer-function
  518.      This user option holds the function to call to select a buffer
  519.      from the `Buffers' menu.  `switch-to-buffer' is a good choice, as
  520.      is `pop-to-buffer'.
  521.  
  522. 
  523. File: lispref.info,  Node: Dialog Boxes,  Next: Toolbar,  Prev: Menus,  Up: Top
  524.  
  525. Dialog Boxes
  526. ************
  527.  
  528. * Menu:
  529.  
  530. * Dialog Box Format::
  531. * Dialog Box Functions::
  532.  
  533. 
  534. File: lispref.info,  Node: Dialog Box Format,  Next: Dialog Box Functions,  Up: Dialog Boxes
  535.  
  536. Dialog Box Format
  537. =================
  538.  
  539.    A dialog box description is a list.
  540.  
  541.    * The first element of the list is a string to display in the dialog
  542.      box.
  543.  
  544.    * The rest of the elements are descriptions of the dialog box's
  545.      buttons.  Each one is a vector of three elements:
  546.         - The first element is the text of the button.
  547.  
  548.         - The second element is the "callback".
  549.  
  550.         - The third element is `t' or `nil', whether this button is
  551.           selectable.
  552.  
  553.    If the callback of a button is a symbol, then it must name a command.
  554. It will be invoked with `call-interactively'.  If it is a list, then it
  555. is evaluated with `eval'.
  556.  
  557.    One (and only one) of the buttons may be `nil'.  This marker means
  558. that all following buttons should be flushright instead of flushleft.
  559.  
  560.    The syntax, more precisely:
  561.  
  562.         form        :=  <something to pass to `eval'>
  563.         command    :=  <a symbol or string, to pass to `call-interactively'>
  564.         callback     :=  command | form
  565.         active-p    :=  <t, nil, or a form to evaluate to decide whether this
  566.                  button should be selectable>
  567.         name        :=  <string>
  568.         partition    :=  'nil'
  569.         button    :=  '['  name callback active-p ']'
  570.         dialog    :=  '(' name [ button ]+ [ partition [ button ]+ ] ')'
  571.  
  572. 
  573. File: lispref.info,  Node: Dialog Box Functions,  Prev: Dialog Box Format,  Up: Dialog Boxes
  574.  
  575. Dialog Box Functions
  576. ====================
  577.  
  578.  - Function: popup-dialog-box DBOX-DESC
  579.      This function pops up a dialog box.  DBOX-DESC describes how the
  580.      dialog box will appear (*note Dialog Box Format::.).
  581.  
  582.    *Note Yes-or-No Queries::, for functions to ask a yes/no question
  583. using a dialog box.
  584.  
  585. 
  586. File: lispref.info,  Node: Toolbar,  Next: Scrollbars,  Prev: Dialog Boxes,  Up: Top
  587.  
  588. Toolbar
  589. *******
  590.  
  591. * Menu:
  592.  
  593. * Toolbar Intro::        An introduction.
  594. * Toolbar Descriptor Format::    How to create a toolbar.
  595. * Specifying the Toolbar::    Setting a toolbar's contents.
  596. * Other Toolbar Variables::    Controlling the size of toolbars.
  597.  
  598. 
  599. File: lispref.info,  Node: Toolbar Intro,  Next: Toolbar Descriptor Format,  Up: Toolbar
  600.  
  601. Toolbar Intro
  602. =============
  603.  
  604.    A "toolbar" is a bar of icons displayed along one edge of a frame.
  605. You can view a toolbar as a series of menu shortcuts - the most common
  606. menu options can be accessed with a single click rather than a series
  607. of clicks and/or drags to select the option from a menu.  Consistent
  608. with this, a help string (called the "help-echo") describing what an
  609. icon in the toolbar (called a "toolbar button") does, is displayed in
  610. the minibuffer when the mouse is over the button.
  611.  
  612.    In XEmacs, a toolbar can be displayed along any of the four edges of
  613. the frame, and two or more different edges can be displaying toolbars
  614. simultaneously.  The contents, thickness, and visibility of the
  615. toolbars can be controlled separately, and the values can be
  616. per-buffer, per-frame, etc., using specifiers (*note Specifiers::.).
  617.  
  618.    Normally, there is one toolbar displayed in a frame.  Usually, this
  619. is the standard toolbar, but certain modes will override this and
  620. substitute their own toolbar.  In some cases (e.g. the VM package), a
  621. package will supply its own toolbar along a different edge from the
  622. standard toolbar, so that both can be visible at once.  This standard
  623. toolbar is usually positioned along the top of the frame, but this can
  624. be changed using `set-default-toolbar-position'.
  625.  
  626.    Note that, for each of the toolbar properties (contents, thickness,
  627. and visibility), there is a separate specifier for each of the four
  628. toolbar positions (top, bottom, left, and right), and an additional
  629. specifier for the "default" toolbar, i.e. the toolbar whose position is
  630. controlled by `set-default-toolbar-position'.  The way this works is
  631. that `set-default-toolbar-position' arranges things so that the
  632. appropriate position-specific specifiers for the default position
  633. inherit from the corresponding default specifiers.  That way, if the
  634. position-specific specifier does not give a value (which it usually
  635. doesn't), then the value from the default specifier applies.  If you
  636. want to control the default toolbar, you just change the default
  637. specifiers, and everything works.  A package such as VM that wants to
  638. put its own toolbar in a different location from the default just sets
  639. the position-specific specifiers, and if the user sets the default
  640. toolbar to the same position, it will just not be visible.
  641.  
  642. 
  643. File: lispref.info,  Node: Toolbar Descriptor Format,  Next: Specifying the Toolbar,  Prev: Toolbar Intro,  Up: Toolbar
  644.  
  645. Toolbar Descriptor Format
  646. =========================
  647.  
  648.    The contents of a toolbar are specified using a "toolbar descriptor".
  649. The format of a toolbar descriptor is a list of "toolbar button
  650. descriptors".  Each toolbar button descriptor is a vector in one of the
  651. following formats:
  652.  
  653.    * `[GLYPH-LIST FUNCTION ENABLED-P HELP]'
  654.  
  655.    * `[:style 2D-OR-3D]'
  656.  
  657.    * `[:style 2D-OR-3D :size WIDTH-OR-HEIGHT]'
  658.  
  659.    * `[:size WIDTH-OR-HEIGHT :style 2D-OR-3D]'
  660.  
  661.    Optionally, one of the toolbar button descriptors may be `nil'
  662. instead of a vector; this signifies the division between the toolbar
  663. buttons that are to be displayed flush-left, and the buttons to be
  664. displayed flush-right.
  665.  
  666.    The first vector format above specifies a normal toolbar button; the
  667. others specify blank areas in the toolbar.
  668.  
  669.    For the first vector format:
  670.  
  671.    * GLYPH-LIST should be a list of one to six glyphs (as created by
  672.      `make-glyph') or a symbol whose value is such a list.  The first
  673.      glyph, which must be provided, is the glyph used to display the
  674.      toolbar button when it is in the "up" (not pressed) state.  The
  675.      optional second glyph is for displaying the button when it is in
  676.      the "down" (pressed) state.  The optional third glyph is for when
  677.      the button is disabled.  The last three glyphs are for displaying
  678.      the button in the "up", "down", and "disabled" states,
  679.      respectively, but are used when the user has called for captioned
  680.      toolbar buttons (using `toolbar-buttons-captioned-p').  The
  681.      function `toolbar-make-button-list' is useful in creating these
  682.      glyph lists.
  683.  
  684.    * Even if you do not provide separate down-state and disabled-state
  685.      glyphs, the user will still get visual feedback to indicate which
  686.      state the button is in.  Buttons in the up-state are displayed
  687.      with a shadowed border that gives a raised appearance to the
  688.      button.  Buttons in the down-state are displayed with shadows that
  689.      give a recessed appearance.  Buttons in the disabled state are
  690.      displayed with no shadows, giving a 2-d effect.
  691.  
  692.    * If some of the toolbar glyphs are not provided, they inherit as
  693.      follows:
  694.  
  695.                UP:                up
  696.                DOWN:              down -> up
  697.                DISABLED:          disabled -> up
  698.                CAP-UP:            cap-up -> up
  699.                CAP-DOWN:          cap-down -> cap-up -> down -> up
  700.                CAP-DISABLED:      cap-disabled -> cap-up -> disabled -> up
  701.  
  702.    * The second element FUNCTION is a function to be called when the
  703.      toolbar button is activated (i.e. when the mouse is released over
  704.      the toolbar button, if the press occurred in the toolbar).  It can
  705.      be any form accepted by `call-interactively', since this is how it
  706.      is invoked.
  707.  
  708.    * The third element ENABLED-P specifies whether the toolbar button
  709.      is enabled (disabled buttons do nothing when they are activated,
  710.      and are displayed differently; see above).  It should be either a
  711.      boolean or a form that evaluates to a boolean.
  712.  
  713.    * The fourth element HELP, if non-`nil', should be a string.  This
  714.      string is displayed in the echo area when the mouse passes over the
  715.      toolbar button.
  716.  
  717.    For the other vector formats (specifying blank areas of the toolbar):
  718.  
  719.    * 2D-OR-3D should be one of the symbols `2d' or `3d', indicating
  720.      whether the area is displayed with shadows (giving it a raised,
  721.      3-d appearance) or without shadows (giving it a flat appearance).
  722.  
  723.    * WIDTH-OR-HEIGHT specifies the length, in pixels, of the blank
  724.      area.  If omitted, it defaults to a device-specific value (8
  725.      pixels for X devices).
  726.  
  727.  - Function: toolbar-make-button-list UP &optional DOWN DISABLED CAP-UP
  728.           CAP-DOWN CAP-DISABLED
  729.      This function calls `make-glyph' on each arg and returns a list of
  730.      the results.  This is useful for setting the first argument of a
  731.      toolbar button descriptor (typically, the result of this function
  732.      is assigned to a symbol, which is specified as the first argument
  733.      of the toolbar button descriptor).
  734.  
  735.  - Function: check-toolbar-button-syntax BUTTON &optional NOERROR
  736.      Verify the syntax of entry BUTTON in a toolbar description list.
  737.      If you want to verify the syntax of a toolbar description list as a
  738.      whole, use `check-valid-instantiator' with a specifier type of
  739.      `toolbar'.
  740.  
  741. 
  742. File: lispref.info,  Node: Specifying the Toolbar,  Next: Other Toolbar Variables,  Prev: Toolbar Descriptor Format,  Up: Toolbar
  743.  
  744. Specifying the Toolbar
  745. ======================
  746.  
  747.    In order to specify the contents of a toolbar, set one of the
  748. specifier variables `default-toolbar', `top-toolbar', `bottom-toolbar',
  749. `left-toolbar', or `right-toolbar'.  These are specifiers, which means
  750. you set them with `set-specifier' and query them with `specifier-specs'
  751. or `specifier-instance'.  You will get an error if you try to set them
  752. using `setq'.  The valid instantiators for these specifiers are toolbar
  753. descriptors, as described above.  *Note Specifiers:: for more
  754. information.
  755.  
  756.    Most of the time, you will set `default-toolbar', which allows the
  757. user to choose where the toolbar should go.
  758.  
  759.  - Specifier: default-toolbar
  760.      The position of this toolbar is specified in the function
  761.      `default-toolbar-position'.  If the corresponding
  762.      position-specific toolbar (e.g. `top-toolbar' if
  763.      `default-toolbar-position' is `top') does not specify a toolbar in
  764.      a particular domain, then the value of `default-toolbar' in that
  765.      domain, of any, will be used instead.
  766.  
  767.    Note that the toolbar at any particular position will not be
  768. displayed unless its thickness (width or height, depending on
  769. orientation) is non-zero and its visibility status is true.  The
  770. thickness is controlled by the specifiers `top-toolbar-height',
  771. `bottom-toolbar-height', `left-toolbar-width', and
  772. `right-toolbar-width', and the visibility status is controlled by the
  773. specifiers `top-toolbar-visible-p', `bottom-toolbar-visible-p',
  774. `left-toolbar-visible-p', and `right-toolbar-visible-p' (*note Other
  775. Toolbar Variables::.).
  776.  
  777.  - Function: set-default-toolbar-position POSITION
  778.      This function sets the position that the `default-toolbar' will be
  779.      displayed at.  Valid positions are the symbols `top', `bottom',
  780.      `left' and `right'.  What this actually does is set the fallback
  781.      specifier for the position-specific specifier corresponding to the
  782.      given position to `default-toolbar', and set the fallbacks for the
  783.      other position-specific specifiers to `nil'.  It also does the
  784.      same thing for the position-specific thickness and visibility
  785.      specifiers, which inherit from one of `default-toolbar-height' or
  786.      `default-toolbar-width', and from `default-toolbar-visible-p',
  787.      respectively (*note Other Toolbar Variables::.).
  788.  
  789.  - Function: default-toolbar-position
  790.      This function returns the position that the `default-toolbar' will
  791.      be displayed at.
  792.  
  793.    You can also explicitly set a toolbar at a particular position.  When
  794. redisplay determines what to display at a particular position in a
  795. particular domain (i.e. window), it first consults the position-specific
  796. toolbar.  If that does not yield a toolbar descriptor, the
  797. `default-toolbar' is consulted if `default-toolbar-position' indicates
  798. this position.
  799.  
  800.  - Specifier: top-toolbar
  801.      Specifier for the toolbar at the top of the frame.
  802.  
  803.  - Specifier: bottom-toolbar
  804.      Specifier for the toolbar at the bottom of the frame.
  805.  
  806.  - Specifier: left-toolbar
  807.      Specifier for the toolbar at the left edge of the frame.
  808.  
  809.  - Specifier: right-toolbar
  810.      Specifier for the toolbar at the right edge of the frame.
  811.  
  812.  - Function: toolbar-specifier-p OBJECT
  813.      This function returns non-nil if OBJECT is a toolbar specifier.
  814.      Toolbar specifiers are the actual objects contained in the toolbar
  815.      variables described above, and their valid instantiators are
  816.      toolbar descriptors (*note Toolbar Descriptor Format::.).
  817.  
  818. 
  819. File: lispref.info,  Node: Other Toolbar Variables,  Prev: Specifying the Toolbar,  Up: Toolbar
  820.  
  821. Other Toolbar Variables
  822. =======================
  823.  
  824.    The variables to control the toolbar thickness, visibility status,
  825. and captioned status are all specifiers.  *Note Specifiers::.
  826.  
  827.  - Specifier: default-toolbar-height
  828.      This specifies the height of the default toolbar, if it's oriented
  829.      horizontally.  The position of the default toolbar is specified by
  830.      the function `set-default-toolbar-position'.  If the corresponding
  831.      position-specific toolbar thickness specifier (e.g.
  832.      `top-toolbar-height' if `default-toolbar-position' is `top') does
  833.      not specify a thickness in a particular domain (a window or a
  834.      frame), then the value of `default-toolbar-height' or
  835.      `default-toolbar-width' (depending on the toolbar orientation) in
  836.      that domain, if any, will be used instead.
  837.  
  838.  - Specifier: default-toolbar-width
  839.      This specifies the width of the default toolbar, if it's oriented
  840.      vertically.  This behaves like `default-toolbar-height'.
  841.  
  842.    Note that `default-toolbar-height' is only used when
  843. `default-toolbar-position' is `top' or `bottom', and
  844. `default-toolbar-width' is only used when `default-toolbar-position' is
  845. `left' or `right'.
  846.  
  847.  - Specifier: top-toolbar-height
  848.      This specifies the height of the top toolbar.
  849.  
  850.  - Specifier: bottom-toolbar-height
  851.      This specifies the height of the bottom toolbar.
  852.  
  853.  - Specifier: left-toolbar-width
  854.      This specifies the width of the left toolbar.
  855.  
  856.  - Specifier: right-toolbar-width
  857.      This specifies the width of the right toolbar.
  858.  
  859.    Note that all of the position-specific toolbar thickness specifiers
  860. have a fallback value of zero when they do not correspond to the
  861. default toolbar.  Therefore, you will have to set a non-zero thickness
  862. value if you want a position-specific toolbar to be displayed.
  863.  
  864.  - Specifier: default-toolbar-visible-p
  865.      This specifies whether the default toolbar is visible.  The
  866.      position of the default toolbar is specified by the function
  867.      `set-default-toolbar-position'.  If the corresponding
  868.      position-specific toolbar visibility specifier (e.g.
  869.      `top-toolbar-visible-p' if `default-toolbar-position' is `top')
  870.      does not specify a visible-p value in a particular domain (a
  871.      window or a frame), then the value of `default-toolbar-visible-p'
  872.      in that domain, if any, will be used instead.
  873.  
  874.  - Specifier: top-toolbar-visible-p
  875.      This specifies whether the top toolbar is visible.
  876.  
  877.  - Specifier: bottom-toolbar-visible-p
  878.      This specifies whether the bottom toolbar is visible.
  879.  
  880.  - Specifier: left-toolbar-visible-p
  881.      This specifies whether the left toolbar is visible.
  882.  
  883.  - Specifier: right-toolbar-visible-p
  884.      This specifies whether the right toolbar is visible.
  885.  
  886.    `default-toolbar-visible-p' and all of the position-specific toolbar
  887. visibility specifiers have a fallback value of true.
  888.  
  889.    Internally, toolbar thickness and visibility specifiers are
  890. instantiated in both window and frame domains, for different purposes.
  891. The value in the domain of a frame's selected window specifies the
  892. actual toolbar thickness or visibility that you will see in that frame.
  893. The value in the domain of a frame itself specifies the toolbar
  894. thickness or visibility that is used in frame geometry calculations.
  895.  
  896.    Thus, for example, if you set the frame width to 80 characters and
  897. the left toolbar width for that frame to 68 pixels, then the frame will
  898. be sized to fit 80 characters plus a 68-pixel left toolbar.  If you then
  899. set the left toolbar width to 0 for a particular buffer (or if that
  900. buffer does not specify a left toolbar or has a nil value specified for
  901. `left-toolbar-visible-p'), you will find that, when that buffer is
  902. displayed in the selected window, the window will have a width of 86 or
  903. 87 characters - the frame is sized for a 68-pixel left toolbar but the
  904. selected window specifies that the left toolbar is not visible, so it is
  905. expanded to take up the slack.
  906.  
  907.  - Specifier: toolbar-buttons-captioned-p
  908.      Whether toolbar buttons are captioned.  This affects which glyphs
  909.      from a toolbar button descriptor are chosen.  *Note Toolbar
  910.      Descriptor Format::.
  911.  
  912.    You can also reset the toolbar to what it was when XEmacs started up.
  913.  
  914.  - Constant: initial-toolbar-spec
  915.      The toolbar descriptor used to initialize `default-toolbar' at
  916.      startup.
  917.  
  918. 
  919. File: lispref.info,  Node: Scrollbars,  Next: Modes,  Prev: Toolbar,  Up: Top
  920.  
  921. scrollbars
  922. **********
  923.  
  924.    Not yet documented.
  925.  
  926. 
  927. File: lispref.info,  Node: Modes,  Next: Documentation,  Prev: Scrollbars,  Up: Top
  928.  
  929. Major and Minor Modes
  930. *********************
  931.  
  932.    A "mode" is a set of definitions that customize XEmacs and can be
  933. turned on and off while you edit.  There are two varieties of modes:
  934. "major modes", which are mutually exclusive and used for editing
  935. particular kinds of text, and "minor modes", which provide features
  936. that users can enable individually.
  937.  
  938.    This chapter describes how to write both major and minor modes, how
  939. to indicate them in the modeline, and how they run hooks supplied by the
  940. user.  For related topics such as keymaps and syntax tables, see *Note
  941. Keymaps::, and *Note Syntax Tables::.
  942.  
  943. * Menu:
  944.  
  945. * Major Modes::        Defining major modes.
  946. * Minor Modes::        Defining minor modes.
  947. * Modeline Format::    Customizing the text that appears in the modeline.
  948. * Hooks::              How to use hooks; how to write code that provides hooks.
  949.  
  950. 
  951. File: lispref.info,  Node: Major Modes,  Next: Minor Modes,  Up: Modes
  952.  
  953. Major Modes
  954. ===========
  955.  
  956.    Major modes specialize XEmacs for editing particular kinds of text.
  957. Each buffer has only one major mode at a time.
  958.  
  959.    The least specialized major mode is called "Fundamental mode".  This
  960. mode has no mode-specific definitions or variable settings, so each
  961. XEmacs command behaves in its default manner, and each option is in its
  962. default state.  All other major modes redefine various keys and options.
  963. For example, Lisp Interaction mode provides special key bindings for
  964. <LFD> (`eval-print-last-sexp'), <TAB> (`lisp-indent-line'), and other
  965. keys.
  966.  
  967.    When you need to write several editing commands to help you perform a
  968. specialized editing task, creating a new major mode is usually a good
  969. idea.  In practice, writing a major mode is easy (in contrast to
  970. writing a minor mode, which is often difficult).
  971.  
  972.    If the new mode is similar to an old one, it is often unwise to
  973. modify the old one to serve two purposes, since it may become harder to
  974. use and maintain.  Instead, copy and rename an existing major mode
  975. definition and alter the copy--or define a "derived mode" (*note
  976. Derived Modes::.).  For example, Rmail Edit mode, which is in
  977. `emacs/lisp/rmailedit.el', is a major mode that is very similar to Text
  978. mode except that it provides three additional commands.  Its definition
  979. is distinct from that of Text mode, but was derived from it.
  980.  
  981.    Rmail Edit mode is an example of a case where one piece of text is
  982. put temporarily into a different major mode so it can be edited in a
  983. different way (with ordinary XEmacs commands rather than Rmail).  In
  984. such cases, the temporary major mode usually has a command to switch
  985. back to the buffer's usual mode (Rmail mode, in this case).  You might
  986. be tempted to present the temporary redefinitions inside a recursive
  987. edit and restore the usual ones when the user exits; but this is a bad
  988. idea because it constrains the user's options when it is done in more
  989. than one buffer: recursive edits must be exited most-recently-entered
  990. first.  Using alternative major modes avoids this limitation.  *Note
  991. Recursive Editing::.
  992.  
  993.    The standard XEmacs Lisp library directory contains the code for
  994. several major modes, in files including `text-mode.el', `texinfo.el',
  995. `lisp-mode.el', `c-mode.el', and `rmail.el'.  You can look at these
  996. libraries to see how modes are written.  Text mode is perhaps the
  997. simplest major mode aside from Fundamental mode.  Rmail mode is a
  998. complicated and specialized mode.
  999.  
  1000. * Menu:
  1001.  
  1002. * Major Mode Conventions::  Coding conventions for keymaps, etc.
  1003. * Example Major Modes::     Text mode and Lisp modes.
  1004. * Auto Major Mode::         How XEmacs chooses the major mode automatically.
  1005. * Mode Help::               Finding out how to use a mode.
  1006. * Derived Modes::           Defining a new major mode based on another major
  1007.                               mode.
  1008.  
  1009. 
  1010. File: lispref.info,  Node: Major Mode Conventions,  Next: Example Major Modes,  Up: Major Modes
  1011.  
  1012. Major Mode Conventions
  1013. ----------------------
  1014.  
  1015.    The code for existing major modes follows various coding conventions,
  1016. including conventions for local keymap and syntax table initialization,
  1017. global names, and hooks.  Please follow these conventions when you
  1018. define a new major mode:
  1019.  
  1020.    * Define a command whose name ends in `-mode', with no arguments,
  1021.      that switches to the new mode in the current buffer.  This command
  1022.      should set up the keymap, syntax table, and local variables in an
  1023.      existing buffer without changing the buffer's text.
  1024.  
  1025.    * Write a documentation string for this command that describes the
  1026.      special commands available in this mode.  `C-h m'
  1027.      (`describe-mode') in your mode will display this string.
  1028.  
  1029.      The documentation string may include the special documentation
  1030.      substrings, `\[COMMAND]', `\{KEYMAP}', and `\<KEYMAP>', that
  1031.      enable the documentation to adapt automatically to the user's own
  1032.      key bindings.  *Note Keys in Documentation::.
  1033.  
  1034.    * The major mode command should start by calling
  1035.      `kill-all-local-variables'.  This is what gets rid of the local
  1036.      variables of the major mode previously in effect.
  1037.  
  1038.    * The major mode command should set the variable `major-mode' to the
  1039.      major mode command symbol.  This is how `describe-mode' discovers
  1040.      which documentation to print.
  1041.  
  1042.    * The major mode command should set the variable `mode-name' to the
  1043.      "pretty" name of the mode, as a string.  This appears in the mode
  1044.      line.
  1045.  
  1046.    * Since all global names are in the same name space, all the global
  1047.      variables, constants, and functions that are part of the mode
  1048.      should have names that start with the major mode name (or with an
  1049.      abbreviation of it if the name is long).  *Note Style Tips::.
  1050.  
  1051.    * The major mode should usually have its own keymap, which is used
  1052.      as the local keymap in all buffers in that mode.  The major mode
  1053.      function should call `use-local-map' to install this local map.
  1054.      *Note Active Keymaps::, for more information.
  1055.  
  1056.      This keymap should be kept in a global variable named
  1057.      `MODENAME-mode-map'.  Normally the library that defines the mode
  1058.      sets this variable.
  1059.  
  1060.    * The mode may have its own syntax table or may share one with other
  1061.      related modes.  If it has its own syntax table, it should store
  1062.      this in a variable named `MODENAME-mode-syntax-table'.  *Note
  1063.      Syntax Tables::.
  1064.  
  1065.    * The mode may have its own abbrev table or may share one with other
  1066.      related modes.  If it has its own abbrev table, it should store
  1067.      this in a variable named `MODENAME-mode-abbrev-table'.  *Note
  1068.      Abbrev Tables::.
  1069.  
  1070.    * Use `defvar' to set mode-related variables, so that they are not
  1071.      reinitialized if they already have a value.  (Such reinitialization
  1072.      could discard customizations made by the user.)
  1073.  
  1074.    * To make a buffer-local binding for an Emacs customization
  1075.      variable, use `make-local-variable' in the major mode command, not
  1076.      `make-variable-buffer-local'.  The latter function would make the
  1077.      variable local to every buffer in which it is subsequently set,
  1078.      which would affect buffers that do not use this mode.  It is
  1079.      undesirable for a mode to have such global effects.  *Note
  1080.      Buffer-Local Variables::.
  1081.  
  1082.      It's ok to use `make-variable-buffer-local', if you wish, for a
  1083.      variable used only within a single Lisp package.
  1084.  
  1085.    * Each major mode should have a "mode hook" named
  1086.      `MODENAME-mode-hook'.  The major mode command should run that
  1087.      hook, with `run-hooks', as the very last thing it does. *Note
  1088.      Hooks::.
  1089.  
  1090.    * The major mode command may also run the hooks of some more basic
  1091.      modes.  For example, `indented-text-mode' runs `text-mode-hook' as
  1092.      well as `indented-text-mode-hook'.  It may run these other hooks
  1093.      immediately before the mode's own hook (that is, after everything
  1094.      else), or it may run them earlier.
  1095.  
  1096.    * If something special should be done if the user switches a buffer
  1097.      from this mode to any other major mode, the mode can set a local
  1098.      value for `change-major-mode-hook'.
  1099.  
  1100.    * If this mode is appropriate only for specially-prepared text, then
  1101.      the major mode command symbol should have a property named
  1102.      `mode-class' with value `special', put on as follows:
  1103.  
  1104.           (put 'funny-mode 'mode-class 'special)
  1105.  
  1106.      This tells XEmacs that new buffers created while the current
  1107.      buffer has Funny mode should not inherit Funny mode.  Modes such
  1108.      as Dired, Rmail, and Buffer List use this feature.
  1109.  
  1110.    * If you want to make the new mode the default for files with certain
  1111.      recognizable names, add an element to `auto-mode-alist' to select
  1112.      the mode for those file names.  If you define the mode command to
  1113.      autoload, you should add this element in the same file that calls
  1114.      `autoload'.  Otherwise, it is sufficient to add the element in the
  1115.      file that contains the mode definition.  *Note Auto Major Mode::.
  1116.  
  1117.    * In the documentation, you should provide a sample `autoload' form
  1118.      and an example of how to add to `auto-mode-alist', that users can
  1119.      include in their `.emacs' files.
  1120.  
  1121.    * The top-level forms in the file defining the mode should be
  1122.      written so that they may be evaluated more than once without
  1123.      adverse consequences.  Even if you never load the file more than
  1124.      once, someone else will.
  1125.  
  1126.  - Variable: change-major-mode-hook
  1127.      This normal hook is run by `kill-all-local-variables' before it
  1128.      does anything else.  This gives major modes a way to arrange for
  1129.      something special to be done if the user switches to a different
  1130.      major mode.  For best results, make this variable buffer-local, so
  1131.      that it will disappear after doing its job and will not interfere
  1132.      with the subsequent major mode.  *Note Hooks::.
  1133.  
  1134.